IRIX Base Documentation 1998 November/IRIX 6.5.2 Base Documentation November 1998.img/usr/share/catman/u_man/cat1/exstr.z/exstr

Text File | 1998-10-20 | 16KB | 265 lines

eeeexxxxssssttttrrrr((((1111))))                                                              eeeexxxxssssttttrrrr((((1111))))



NNNNAAAAMMMMEEEE
     _eeee_xxxx_ssss_tttt_rrrr - extract strings from source files

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     _eeee_xxxx_ssss_tttt_rrrr _f_i_l_e...
     _eeee_xxxx_ssss_tttt_rrrr _----_eeee _f_i_l_e...
     _eeee_xxxx_ssss_tttt_rrrr _----_rrrr [_----_dddd] _f_i_l_e...

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     The _eeee_xxxx_ssss_tttt_rrrr utility is used to extract strings from C language source files
     and replace them by calls to the message retrieval function [see
     _gggg_eeee_tttt_tttt_xxxx_tttt(3C)].  This utility will extract all character strings surrounded
     by double quotes, not just strings used as arguments to the _pppp_rrrr_iiii_nnnn_tttt_ffff
     command or the _pppp_rrrr_iiii_nnnn_tttt_ffff routine.  In the first form, _eeee_xxxx_ssss_tttt_rrrr finds all
     strings in the source files and writes them on the standard output.  Each
     string is preceded by the source file name and a colon.  The meanings of
     the options are:

     _----_eeee      Extract a list of strings from the named C language source files,
             with positional information.  This list is produced on standard
             output in the following format:

                 _f_i_l_e:_l_i_n_e:_p_o_s_i_t_i_o_n:_m_s_g_f_i_l_e:_m_s_g_n_u_m:_s_t_r_i_n_g

                 _f_i_l_e      the name of a C language source file
                 _l_i_n_e      line number in the file
                 _p_o_s_i_t_i_o_n  character position in the line
                 _m_s_g_f_i_l_e   null
                 _m_s_g_n_u_m    null
                 _s_t_r_i_n_g    the extracted text string

             Normally you would redirect this output into a file.  Then you
             would edit this file to add the values you want to use for
             _m_s_g_f_i_l_e and _m_s_g_n_u_m:

                 _m_s_g_f_i_l_e   the file that contains the text strings that will
                           replace _s_t_r_i_n_g.  A file with this name must be
                           created and installed in the appropriate place by
                           the _mmmm_kkkk_mmmm_ssss_gggg_ssss(1) utility.

                 _m_s_g_n_u_m    the sequence number of the string in _m_s_g_f_i_l_e.

             The next step is to use _eeee_xxxx_ssss_tttt_rrrr _----_rrrr to replace _s_t_r_i_n_gs in _f_i_l_e.

     _----_rrrr      Replace strings in a C language source file with function calls
             to the message retrieval function _gggg_eeee_tttt_tttt_xxxx_tttt.

     _----_dddd      This option is used together with the _----_rrrr option.  If the message
             retrieval fails when _gggg_eeee_tttt_tttt_xxxx_tttt is invoked at run time, then the
             extracted string is printed.





                                                                        PPPPaaaaggggeeee 1111






eeeexxxxssssttttrrrr((((1111))))                                                              eeeexxxxssssttttrrrr((((1111))))



     You would use the capability provided by _eeee_xxxx_ssss_tttt_rrrr on an application program
     that needs to run in an international environment and have messages print
     in more than one language.  _eeee_xxxx_ssss_tttt_rrrr replaces text strings with function
     calls that point at strings in a message database.  The database used
     depends on the runtime value of the _LLLL_CCCC______MMMM_EEEE_SSSS_SSSS_AAAA_GGGG_EEEE_SSSS environment variable [see
     _eeee_nnnn_vvvv_iiii_rrrr_oooo_nnnn(5)].

     The first step is to use _eeee_xxxx_ssss_tttt_rrrr _----_eeee to extract a list of strings and save
     it in a file.  Next, examine this list and determine which strings can be
     translated and subsequently retrieved by the message retrieval function.
     Then, modify this file by deleting lines that can't be translated and,
     for lines that can be translated, by adding the message file names and
     the message numbers as the fourth (_m_s_g_f_i_l_e) and fifth (_m_s_g_n_u_m) entries on
     a line.  The message files named must have been created by _mmmm_kkkk_mmmm_ssss_gggg_ssss(1) and
     exist in _////_uuuu_ssss_rrrr_////_llll_iiii_bbbb_////_llll_oooo_cccc_aaaa_llll_eeee_////_l_o_c_a_l_e_////_LLLL_CCCC______MMMM_EEEE_SSSS_SSSS_AAAA_GGGG_EEEE_SSSS.  The directory _l_o_c_a_l_e
     corresponds to the language in which the text strings are written [see
     _ssss_eeee_tttt_llll_oooo_cccc_aaaa_llll_eeee(3C)].  The message numbers used must correspond to the sequence
     numbers of strings in the message files.

     Now use this modified file as input to _eeee_xxxx_ssss_tttt_rrrr _----_rrrr to produce a new version
     of the original C language source file in which the strings have been
     replaced by calls to the message retrieval function _gggg_eeee_tttt_tttt_xxxx_tttt.  The _m_s_g_f_i_l_e
     and _m_s_g_n_u_m fields are used to construct the first argument to _gggg_eeee_tttt_tttt_xxxx_tttt.
     The second argument to _gggg_eeee_tttt_tttt_xxxx_tttt is printed if the message retrieval fails
     at run time.  This argument is the null string, unless the _----_dddd option is
     used.

     This utility cannot replace strings in all instances. For example, a
     static initialized character string cannot be replaced by a function
     call, or a string could be in the form of an escape sequence that cannot
     be translated.  In order not to break existing code, the files created by
     invoking _eeee_xxxx_ssss_tttt_rrrr _----_eeee must be examined and lines containing strings not
     replaceable by function calls must be deleted. In some cases the code may
     require modifications so that strings can be extracted and replaced by
     calls to the message retrieval function.

EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
     The following examples show uses of _eeee_xxxx_ssss_tttt_rrrr.

     Assume that the file _ffff_oooo_oooo_...._cccc contains two strings:

          _mmmm_aaaa_iiii_nnnn_((((_))))
          _{{{{
               _pppp_rrrr_iiii_nnnn_tttt_ffff_((((_""""_TTTT_hhhh_iiii_ssss _iiii_ssss _aaaa_nnnn _eeee_xxxx_aaaa_mmmm_pppp_llll_eeee_\\\\_nnnn_""""_))))_;;;;
               _pppp_rrrr_iiii_nnnn_tttt_ffff_((((_""""_HHHH_eeee_llll_llll_oooo _wwww_oooo_rrrr_llll_dddd_!!!!_\\\\_nnnn_""""_))))_;;;;
          _}}}}

     The _eeee_xxxx_ssss_tttt_rrrr utility, invoked with the argument _ffff_oooo_oooo_...._cccc, extracts strings from
     the named file and prints them on the standard output.






                                                                        PPPPaaaaggggeeee 2222






eeeexxxxssssttttrrrr((((1111))))                                                              eeeexxxxssssttttrrrr((((1111))))



     _eeee_xxxx_ssss_tttt_rrrr _ffff_oooo_oooo_...._cccc produces the following output:

          _ffff_oooo_oooo_...._cccc_::::_TTTT_hhhh_iiii_ssss _iiii_ssss _aaaa_nnnn _eeee_xxxx_aaaa_mmmm_pppp_llll_eeee_\\\\_nnnn
          _ffff_oooo_oooo_...._cccc_::::_HHHH_eeee_llll_llll_oooo _wwww_oooo_rrrr_llll_dddd_!!!!_\\\\_nnnn

     _eeee_xxxx_ssss_tttt_rrrr _----_eeee _ffff_oooo_oooo_...._cccc _>>>> _ffff_oooo_oooo_...._ssss_tttt_rrrr_iiii_nnnn_gggg_ssss_oooo_uuuu_tttt produces the following output in the file
     _ffff_oooo_oooo_...._ssss_tttt_rrrr_iiii_nnnn_gggg_ssss_oooo_uuuu_tttt:

          _ffff_oooo_oooo_...._cccc_::::_3333_::::_8888_::::_::::_::::_TTTT_hhhh_iiii_ssss _iiii_ssss _aaaa_nnnn _eeee_xxxx_aaaa_mmmm_pppp_llll_eeee_\\\\_nnnn
          _ffff_oooo_oooo_...._cccc_::::_4444_::::_8888_::::_::::_::::_HHHH_eeee_llll_llll_oooo _wwww_oooo_rrrr_llll_dddd_!!!!_\\\\_nnnn

     You must edit _ffff_oooo_oooo_...._ssss_tttt_rrrr_iiii_nnnn_gggg_ssss_oooo_uuuu_tttt to add the values you want to use for the
     _m_s_g_f_i_l_e and _m_s_g_n_u_m fields before these strings can be replaced by calls
     to the retrieval function.  If _UUUU_XXXX is the name of the message file, and
     the numbers _1111 and _2222 represent the sequence number of the strings in the
     file, here is what _ffff_oooo_oooo_...._ssss_tttt_rrrr_iiii_nnnn_gggg_ssss_oooo_uuuu_tttt looks like after you add this
     information:

          _ffff_oooo_oooo_...._cccc_::::_3333_::::_8888_::::_UUUU_XXXX_::::_1111_::::_TTTT_hhhh_iiii_ssss _iiii_ssss _aaaa_nnnn _eeee_xxxx_aaaa_mmmm_pppp_llll_eeee_\\\\_nnnn
          _ffff_oooo_oooo_...._cccc_::::_4444_::::_8888_::::_UUUU_XXXX_::::_2222_::::_HHHH_eeee_llll_llll_oooo _wwww_oooo_rrrr_llll_dddd_!!!!_\\\\_nnnn

     The _eeee_xxxx_ssss_tttt_rrrr utility can now be invoked with the _----_rrrr option to replace the
     strings in the source file by calls to the message retrieval function
     _gggg_eeee_tttt_tttt_xxxx_tttt.

     _eeee_xxxx_ssss_tttt_rrrr _----_rrrr _ffff_oooo_oooo_...._cccc _<<<<_ffff_oooo_oooo_...._ssss_tttt_rrrr_iiii_nnnn_gggg_ssss_oooo_uuuu_tttt _>>>>_iiii_nnnn_tttt_llll_ffff_oooo_oooo_...._cccc produces the following output:

          _eeee_xxxx_tttt_eeee_rrrr_nnnn _cccc_hhhh_aaaa_rrrr _****_gggg_eeee_tttt_tttt_xxxx_tttt_((((_))))_;;;;
          _mmmm_aaaa_iiii_nnnn_((((_))))
          _{{{{
               _pppp_rrrr_iiii_nnnn_tttt_ffff_((((_gggg_eeee_tttt_tttt_xxxx_tttt_((((_""""_UUUU_XXXX_::::_1111_""""_,,,, _""""_""""_))))_))))_;;;;
               _pppp_rrrr_iiii_nnnn_tttt_ffff_((((_gggg_eeee_tttt_tttt_xxxx_tttt_((((_""""_UUUU_XXXX_::::_2222_""""_,,,, _""""_""""_))))_))))_;;;;
          _}}}}

     _eeee_xxxx_ssss_tttt_rrrr _----_rrrr_dddd _ffff_oooo_oooo_...._cccc _<<<<_ffff_oooo_oooo_...._ssss_tttt_rrrr_iiii_nnnn_gggg_ssss_oooo_uuuu_tttt _>>>>_iiii_nnnn_tttt_llll_ffff_oooo_oooo_...._cccc uses the extracted strings as
     a second argument to _gggg_eeee_tttt_tttt_xxxx_tttt.

          _eeee_xxxx_tttt_eeee_rrrr_nnnn _cccc_hhhh_aaaa_rrrr _****_gggg_eeee_tttt_tttt_xxxx_tttt_((((_))))_;;;;
          _mmmm_aaaa_iiii_nnnn_((((_))))
          _{{{{
               _pppp_rrrr_iiii_nnnn_tttt_ffff_((((_gggg_eeee_tttt_tttt_xxxx_tttt_((((_""""_UUUU_XXXX_::::_1111_""""_,,,, _""""_TTTT_hhhh_iiii_ssss _iiii_ssss _aaaa_nnnn _eeee_xxxx_aaaa_mmmm_pppp_llll_eeee_\\\\_nnnn_""""_))))_))))_;;;;
               _pppp_rrrr_iiii_nnnn_tttt_ffff_((((_gggg_eeee_tttt_tttt_xxxx_tttt_((((_""""_UUUU_XXXX_::::_2222_""""_,,,, _""""_HHHH_eeee_llll_llll_oooo _wwww_oooo_rrrr_llll_dddd_!!!!_\\\\_nnnn_""""_))))_))))_;;;;
          _}}}}

FFFFIIIILLLLEEEESSSS
     _////_uuuu_ssss_rrrr_////_llll_iiii_bbbb_////_llll_oooo_cccc_aaaa_llll_eeee_////_l_o_c_a_l_e_////_LLLL_CCCC______MMMM_EEEE_SSSS_SSSS_AAAA_GGGG_EEEE_SSSS_////_****
                              files created by _mmmm_kkkk_mmmm_ssss_gggg_ssss(1)

SSSSEEEEEEEE AAAALLLLSSSSOOOO
     _gggg_eeee_tttt_tttt_xxxx_tttt(1), _mmmm_kkkk_mmmm_ssss_gggg_ssss(1), _pppp_rrrr_iiii_nnnn_tttt_ffff(1), _ssss_rrrr_cccc_hhhh_tttt_xxxx_tttt(1), _gggg_eeee_tttt_tttt_xxxx_tttt(3C), _pppp_rrrr_iiii_nnnn_tttt_ffff(3S),
     _ssss_eeee_tttt_llll_oooo_cccc_aaaa_llll_eeee(3C), _eeee_nnnn_vvvv_iiii_rrrr_oooo_nnnn(5).




                                                                        PPPPaaaaggggeeee 3333






eeeexxxxssssttttrrrr((((1111))))                                                              eeeexxxxssssttttrrrr((((1111))))



DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
     The error messages produced by _eeee_xxxx_ssss_tttt_rrrr are intended to be self-explanatory.
     They indicate errors in the command line or format errors encountered
     within the input file.



















































                                                                        PPPPaaaaggggeeee 4444